import SEO from '../components/SEO'

<SEO
  title="Accordion"
  description="Accordions display a list of high-level options that can expand/collapse to reveal more information."
/>

# Accordion

Accordions display a list of high-level options that can expand/collapse to reveal more information.

See `CAccordion`'s <a href="https://github.com/chakra-ui/chakra-ui-vue/blob/master/packages/chakra-ui-core/src/CAccordion/accessibility.md">accessibility report</a>

<carbon-ad />

## Imports

Chakra UI Vue provides 5 Accordion related components:
- `CAccordion`: The wrapper that clones its children to forward its props to the `CAccordionItem`.
- `CAccordionItem`: A single accordion item.
- `CAccordionHeader`: The button that toggles the expand/collapse state of the `CAccordionItem`.
- `CAccordionPanel`: The container for the details to be revealed.
- `CAccordionIcon`: A chevron-down icon that rotates based on the expanded/collapsed state

<br />

```js
import {
  CAccordion,
  CAccordionItem,
  CAccordionHeader,
  CAccordionPanel,
  CAccordionIcon,
} from "@chakra-ui/vue";
```

## Usage

By default, only one accordion item may be expanded. It can only be collapsed again by expanding another accordion item.

```vue live=true
  <c-accordion>
    <c-accordion-item>
      <c-accordion-header>
        <c-box flex="1" text-align="left">
          Section 1 title
        </c-box>
        <c-accordion-icon />
      </c-accordion-header>
      <c-accordion-panel pb="4">
        Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod
        tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim
        veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea
        commodo consequat.
      </c-accordion-panel>
    </c-accordion-item>
    <c-accordion-item>
      <c-accordion-header>
        <c-box flex="1" text-align="left">
          Section 2 title
        </c-box>
        <c-accordion-icon />
      </c-accordion-header>
      <c-accordion-panel pb="4">
        Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod
        tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim
        veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea
        commodo consequat.
      </c-accordion-panel>
    </c-accordion-item>
  </c-accordion>
```

### Expand multiple items
Setting the `allowMultiple` prop to `true` allows the accordion to permit multiple items to be expanded at once.

> If you pass this prop, ensure that the `index` or `defaultIndex` prop is an array.

```vue live=true
  <c-accordion :allow-multiple="true" :default-index="[0]">
    <c-accordion-item>
      <c-accordion-header>
        <c-box flex="1" text-align="left">
          Section 1 title
        </c-box>
        <c-accordion-icon />
      </c-accordion-header>
      <c-accordion-panel pb="4">
        Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod
        tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim
        veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea
        commodo consequat.
      </c-accordion-panel>
    </c-accordion-item>
    <c-accordion-item>
      <c-accordion-header>
        <c-box flex="1" text-align="left">
          Section 2 title
        </c-box>
        <c-accordion-icon />
      </c-accordion-header>
      <c-accordion-panel pb="4">
        Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod
        tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim
        veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea
        commodo consequat.
      </c-accordion-panel>
    </c-accordion-item>
  </c-accordion>
```

### Toggle each accordion item

Setting the `allowToggle` prop to true allows any expanded item to be collapsed again.

```vue live=true
  <c-accordion :allow-toggle="true">
    <c-accordion-item>
      <c-accordion-header>
        <c-box flex="1" text-align="left">
          Section 1 title
        </c-box>
        <c-accordion-icon />
      </c-accordion-header>
      <c-accordion-panel pb="4">
        Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod
        tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim
        veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea
        commodo consequat.
      </c-accordion-panel>
    </c-accordion-item>
    <c-accordion-item>
      <c-accordion-header>
        <c-box flex="1" text-align="left">
          Section 2 title
        </c-box>
        <c-accordion-icon />
      </c-accordion-header>
      <c-accordion-panel pb="4">
        Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod
        tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim
        veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea
        commodo consequat.
      </c-accordion-panel>
    </c-accordion-item>
  </c-accordion>
```

### Styling the expanded state
The `CAccordionHeader` component has `aria-expanded` set to `true` or `false` depending on the state of the `CAccordionItem`.
Use the style prop `_expanded` to style this state.

```vue live=true
<c-accordion-item>
  <c-accordion-header :_expanded="{ bg: 'tomato', color: 'white' }">
    <c-box flex="1" text-align="left">
      Section 1 title
    </c-box>
    <c-accordion-icon />
  </c-accordion-header>
  <c-accordion-panel pb="4">
    Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod
    tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim
    veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea
    commodo consequat.
  </c-accordion-panel>
</c-accordion-item>
```

### Accessing the internal expanded & disabled state
The `CAccordionItem` component exposes a scoped slot with two variables: `isExpanded` and `isDisabled`.
In the example below, we change the icon rendered by the `CAccordionIcon` based on the `CAccordionItems` expanded state.

```vue live=true
<c-accordion :allow-toggle="true">
  <c-accordion-item>
    <c-accordion-header>
      <c-box flex="1" text-align="left">
        Section 1 title
      </c-box>
      <c-accordion-icon />
    </c-accordion-header>
    <c-accordion-panel pb="4">
      Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod
      tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim
      veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea
      commodo consequat.
    </c-accordion-panel>
  </c-accordion-item>
  <c-accordion-item v-slot="{ isExpanded }">
    <c-accordion-header>
      <c-box flex="1" text-align="left">
        Section 2 title
      </c-box>
      <c-accordion-icon size="12px" :name="isExpanded ? 'minus' : 'add'" />
    </c-accordion-header>
    <c-accordion-panel pb="4">
      Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod
      tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim
      veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea
      commodo consequat.
    </c-accordion-panel>
  </c-accordion-item>
</c-accordion>
```

### Accessibility
Pressing **`space`** or **`enter`** when the focus is on the `CAccordionHeader` will toggle (expand or collapse) the accordion item.

# Props
## `CAccordion`
### Props
| Name          | Type                              | Default | Description                                                                                               |
| ------------- | --------------------------------- | ------- | --------------------------------------------------------------------------------------------------------- |
| allowMultiple | `boolean`                         | `false` | If `true`, multiple accordion items can be expanded at once.                                              |
| allowToggle   | `boolean`                         | `false` | If `true`, any expanded accordion item can be collapsed again.                                            |
| index         | `Number` or `Array of Number`     |    0    | The index(es) of the expanded accordion item                                                              |
| defaultIndex  | `Number` or `Array of Number`     |         | The initial index(es) of the expanded accordion item                                                      |

### Events
| Name          | Payload type                      | Default | Description                                                                                               |
| ------------- | --------------------------------- | ------- | --------------------------------------------------------------------------------------------------------- |
| change        | `Number` | `Array of Number`      |         | Event emitted when the accordion items are expanded.                                     |

### Slots
| Name          | Description                               |
| ------------- | ------------------------------------------|
| default       | Slot for `CAccordionItems` components     |



## `CAccordionItem`
### Props
| Name          | Type                                      | Default | Description                                                                                               |
| ------------- | ----------------------------------------- | ------- | --------------------------------------------------------------------------------------------------------- |
| isOpen        | `boolean`                                 | false   | If `true`, expands the accordion in the controlled mode.                                                  |
| defaultIsOpen | `boolean`                                 | false   | If `true`, expands the accordion by on initial mount.                                                     |
| id            | `string`                                  |         | A unique `id` for the accordion item.                                                                     |
| isDisabled    | `boolean`                                 | false   | If `true`, the accordion header will be disabled.                                                         |


### Events
| Name          | Payload type                      | Default | Description                                                                                               |
| ------------- | --------------------------------- | ------- | --------------------------------------------------------------------------------------------------------- |
| change        | `Number` | `Array of Number`      |         | Event emitted when the `CAccordionItem` expands or collapses.                                     |


### Scoped Slots
| Name          | Type                              | Slot    | Default | Description                                                                                               |
| ------------- | --------------------------------- | ------- | ------- | --------------------------------------------------------------------------------------------------------- |
| isExpanded    | `Number` | `Array of Number`      | default |          | Exposes the expanded state of the `CAccordionItem`                                                        |
| isDisabled    | `Number` | `Array of Number`      | default |          | Exposes the disabled state of the `CAccordionItem`                                                        |


## `CAccordionHeader`

### Props
`CAccordionHeader` renders a `button` and composes `CPseudoBox`, this means you can
style it by passing the pseudo style props `_expanded`, `_disabled`, `_hover`,
etc.

## `CAccordionPanel`
`CAccordionPanel` renders a `div` and composes `Collapse` to provide the height
animation.
